#ifndef __IM_COMPONENT_INFO_H__
#define __IM_COMPONENT_INFO_H__

#include <im_base_types.h>
#include <im_object.h>
#include <im_string.h>
#include <im_event_roles.h>

/**
 * @defgroup IMComponentInfo
 * @ingroup PublicIME
 * @{
 */

/**
 * @struct IMComponentInfo
 * @brief IMComponentInfo class is used to hold various information of an
 *        IMBUS component.
 *
 * An IMComponentInfo object contains the following information of an IMBUS
 * component:
 *
 * - Unique ID:
 *   type IMUInt32
 *   An unique id of the component.
 *   The default value of unique id is IM_EVENT_SOURCE_INVALID
 *   The id is allocated and assigned by IMBUS.
 * - Unique string ID (IMString)
 *   An unique string ID of the component. Components registered into IMBUS
 *   shall have unique string IDs, unless the string ID is empty.
 *   In order to make the string ID unique, UUID or URL like string can be used
 *   as string ID, such as "org.imbus.storage.file".
 * - Human readable names for specific languages (IMString, UTF-8 encoding)
 *   Names of the component in specific languages.
 * - Human readable descriptions for specific languages (IMString, UTF-8 encoding)
 *   Descriptions of the component in specific languages.
 * - Path to an icon file
 *   Icon file of the component that will be shown to user.
 * - IMEventRoles
 *   An IMEventRoles object containing event roles supported by the component.
 * - A list of language tags supported by the specified IMBUS component.
 *
 */

IM_BEGIN_DECLS
/** @brief cast the pointer to IMComponentInfo*, return NULL if failed. */
#define IM_COMPONENT_INFO(p)                  (IM_TYPE_INSTANCE_CHECK_CAST((p),IM_TYPE_COMPONENT_INFO,IMComponentInfo))
/** @brief cast the pointer to const IMComponentInfo*, return NULL if failed. */
#define IM_CONST_COMPONENT_INFO(p)            (IM_TYPE_INSTANCE_CHECK_CAST_CONST((p),IM_TYPE_COMPONENT_INFO,IMComponentInfo))
/** @brief cast the pointer to IMComponentInfoClass*, return NULL if failed. */
#define IM_COMPONENT_INFO_CLASS(c)            (IM_TYPE_CLASS_CHECK_CAST((c),IM_TYPE_COMPONENT_INFO,IMComponentInfoClass))
/** @brief tell if the pointer is an instance of IMComponentInfo. */
#define IM_IS_COMPONENT_INFO(p)               (IM_TYPE_INSTANCE_CHECK_TYPE((p),IM_TYPE_COMPONENT_INFO))
/** @brief tell if the pointer is an IMComponentInfoClass. */
#define IM_IS_COMPONENT_INFO_CLASS(c)         (IM_TYPE_CLASS_CHECK_TYPE((c),IM_TYPE_COMPONENT_INFO))
/** @brief get the type id from an instance of IMComponentInfo. */
#define IM_COMPONENT_INFO_GET_CLASS(p)        (IM_TYPE_INSTANCE_GET_CLASS_CAST((p),IM_TYPE_COMPONENT_INFO,IMComponentInfoClass))

typedef struct _IMComponentInfo         IMComponentInfo;
typedef struct _IMComponentInfoClass    IMComponentInfoClass;

/**
 * @brief Creates a new empty IMComponentInfo object.
 *
 * @return  the newly created IMComponentInfo object
 */
IMComponentInfo*    im_component_info_new           ();

/**
 * @brief Creates a new IMComponentInfo object with full parameters.
 *
 * @param string_id   Unique string id of the component
 * @param name        Human readable name of the component, must be in UTF-8
 *                    encoding. The ownership of this object will be assumed by
 *                    the newly created IMComponentInfo object. It's the
 *                    default name without specified language tag.
 * @param desc        Human readable description of the component, must be in UTF-8
 *                    encoding. The ownership of this object will be assumed by
 *                    the newly created IMComponentInfo object. It's the
 *                    default description without specified language tag.
 * @param icon_file   Path to icon file of the component. The ownership of this
 *                    object will be assumed by the newly created
 *                    IMComponentInfo object.
 * @param event_roles IMEventRoles object containing event roles supported by
 *                    the component. The ownership of this object will be
 *                    assumed by the newly created IMComponenInfo object.
 *
 * @return  the newly created IMComponentInfo object.
 */
IMComponentInfo*    im_component_info_new_full      (IMString           *string_id,
                                                     IMString           *name,
                                                     IMString           *desc,
                                                     IMString           *icon_file,
                                                     IMEventRoles       *event_roles);

/**
 * @brief Sets component's unique id stored in a specified IMComponentInfo
 * object to a specified value.
 *
 * The component's unique id shall be allocated by IMBUS.
 *
 * @param info      Pointer to an IMComponentInfo object, for which the unique
 *                  id will be set.
 * @param unique_id Unique id allocated by IMBUS.
 */
void                im_component_info_set_unique_id (IMComponentInfo    *info,
                                                     IMUInt32            unique_id);

/**
 * @brief Gets component's unique id stored in a specified IMComponentInfo
 * object.
 *
 * @param info Pointer to an IMComponentInfo object, of which the unique id
 *             will be returned.
 * @return The component's unique id stored in the specified IMComponentInfo
 *         object.
 */
IMUInt32            im_component_info_get_unique_id (IMComponentInfo    *info);

/**
 * @brief Sets component's string id stored in a specified IMComponentInfo
 * object to a specified value.
 *
 * @param info      Pointer to an IMComponentInfo object, for which the string
 *                  id will be set.
 * @param string_id An IMString object contains the new string id.
 *                  The ownership of this object will be assumed by the
 *                  specified IMComponentInfo object.
 */
void                im_component_info_set_string_id (IMComponentInfo    *info,
                                                     IMString           *string_id);

/**
 * @brief Gets component's string id stored in a specified IMComponentInfo
 * object.
 *
 * @param info Pointer to an IMComponentInfo object, of which the unique id
 *             will be returned.
 * @return The component's string id stored in the specified IMComponentInfo
 *         object. The returned IMString object is owned by the specified
 *         IMComponentInfo object, if caller wants to keep the returned object
 *         a reference of the object must be assumed by the caller.
 *         Caller shall not change the value of returned object.
 */
IMString*           im_component_info_get_string_id (IMComponentInfo    *info);

/**
 * @brief Sets component's human readable name stored in a specified
 * IMComponentInfo object to a specified value.
 *
 * @param info Pointer to an IMComponentInfo object, for which the name
 *             will be set.
 * @param name An IMString object contains the new human readable name.
 *             The ownership of this object will be assumed by the
 *             specified IMComponentInfo object.
 * @param lang A language tag associated to the specified name. NULL means
 *             the default name.
 */
void                im_component_info_set_name      (IMComponentInfo    *info,
                                                     IMString           *name,
                                                     const IMChar       *lang);

/**
 * @brief Gets component's human readable name stored in a specified
 * IMComponentInfo object.
 *
 * @param info Pointer to an IMComponentInfo object, of which the name
 *             will be returned.
 * @param lang A language tag of which the associated name to be retrieved.
 *             NULL means the default name shall be retrieved..
 * @return The component's human readable name stored in the specified
 *         IMComponentInfo object.
 *         The returned IMString object is owned by the specified
 *         IMComponentInfo object, if caller wants to keep the returned
 *         object, a reference of the object must be assumed by the caller.
 *         Caller shall not change the value of returned object.
 */
IMString*           im_component_info_get_name      (IMComponentInfo    *info,
                                                     const IMChar       *lang);

/**
 * @brief Sets component's human readable description stored in a specified
 * IMComponentInfo object to a specified value.
 *
 * @param info Pointer to an IMComponentInfo object, for which the description
 *             will be set.
 * @param desc An IMString object contains the new human readable description.
 *                The ownership of this object will be assumed by the
 *                specified IMComponentInfo object.
 * @param lang A language tag associated to the specified description. NULL
 *             means the default description.
 */
void                im_component_info_set_description(IMComponentInfo   *info,
                                                      IMString          *desc,
                                                      const IMChar      *lang);

/**
 * @brief Gets component's human readable description stored in a specified
 * IMComponentInfo object.
 *
 * @param info Pointer to an IMComponentInfo object, of which the description
 *             will be returned.
 * @param lang A language tag of which the associated name to be retrieved.
 *             NULL means the default description shall be retrieved..
 * @return The component's human readable description stored in the specified
 *         IMComponentInfo object.
 *         The returned IMString object is owned by the specified
 *         IMComponentInfo object, if caller wants to keep the returned
 *         object, a reference of the object must be assumed by the caller.
 *         Caller shall not change the value of returned object.
 */
IMString*           im_component_info_get_description(IMComponentInfo   *info,
                                                      const IMChar      *lang);

/**
 * @brief Sets component's icon file stored in a specified IMComponentInfo
 * object to a specified value.
 *
 * @param info Pointer to an IMComponentInfo object, for which the icon file
 *             will be set.
 * @param icon An IMString object contains the new icon file.
 *             The ownership of this object will be assumed by the
 *             specified IMComponentInfo object.
 */
void                im_component_info_set_icon      (IMComponentInfo    *info,
                                                     IMString           *icon);

/**
 * @brief Gets component's icon file stored in a specified IMComponentInfo
 * object.
 *
 * @param info Pointer to an IMComponentInfo object, of which icon file
 *             will be returned.
 * @return The component's icon file stored in the specified IMComponentInfo
 *         object. The returned IMString object is owned by the specified
 *         IMComponentInfo object, if caller wants to keep the returned
 *         object, a reference of the object must be assumed by the caller.
 *         Caller shall not change the value of returned object.
 */
IMString*           im_component_info_get_icon      (IMComponentInfo    *info);

/**
 * @brief Sets component's event roles stored in a specified IMComponentInfo
 * object to a specified value.
 *
 * @param info Pointer to an IMComponentInfo object, for which the event roles
 *             will be set.
 * @param event_roles An IMEventRoles object contains the new event roles.
 *                    The ownership of this object will be assumed by the
 *                    specified IMComponentInfo object.
 */
void                im_component_info_set_event_roles(IMComponentInfo    *info,
                                                      IMEventRoles       *event_roles);

/**
 * @brief Gets component's event roles stored in a specified IMComponentInfo
 * object.
 *
 * @param info Pointer to an IMComponentInfo object, of which event roles
 *             will be returned.
 * @return The component's event roles stored in the specified IMComponentInfo
 *         object. The returned IMEventRoles object is owned by the specified
 *         IMComponentInfo object, if caller wants to keep the returned
 *         object, a reference of the object must be assumed by the caller.
 *         Caller shall not change the value of returned object.
 */
IMEventRoles*       im_component_info_get_event_roles(IMComponentInfo    *info);

/**
 * @brief Sets component's supported languages to a specified IMComponentInfo
 * object.
 *
 * @param info Pointer to an IMComponentInfo object, for which the supported
 *             languages will be set.
 * @param langs An IMString object contains a list of supported languages.
 *              The ownership of this object will be assumed by the
 *              specified IMComponentInfo object.
 *              The language tag shall be in format "en-us", multiple tags are
 *              separated by comma.
 */
void                im_component_info_set_languages (IMComponentInfo    *info,
                                                     IMString           *langs);

/**
 * @brief Gets component's supported languages from  a specified IMComponentInfo
 * object.
 *
 * @param info Pointer to an IMComponentInfo object, of which the supported
 *             languages will be returned.
 * @return The component's supported languages. The returned IMString object
 *         is owned by the specified IMComponentInfo object, if caller wants
 *         to keep the returned object, a reference of the object must be
 *         assumed by the caller. Caller shall not change the value of returned
 *         object.
 */
IMString*           im_component_info_get_languages (IMComponentInfo    *info);


IM_END_DECLS

#endif
/**  @} */

/*
vi:ts=4:nowrap:ai:expandtab
*/
